ASA DataFest 2024 Workshop

Acknowledgement

• The content is inspired by the following notes and workshop materials:
  • STAT1378 Coding and Communication in Statistics by Thomas Fung at Macquarie University
  • Reproducible Reports with R Markdown https://jminnier-berd-r-courses.netlify.app/03-rmarkdown/03_rmarkdown_slides.html
  • Hello Quarto: Share + Collaborate + Teach + Reimagine https://mine.quarto.pub/hello-quarto/ talk at rstudio::conf(2022) by Mine Çetinkaya-Rundel and Julia Stewart Lowndes
  • Quarto for the curious https://thomasmock.quarto.pub/quarto-curious/ talk at rstudio::conf(2022) by Tom Mock
  • Quarto Guide https://quarto.org/docs/guide/

Motivating Video

What is Quarto?

• Quarto is the next generation of R Markdown for publishing, including dynamic and static documents and multi-lingual programming language support.
• Quarto unifies and extends the R Markdown ecosystem
  • unifies for people who love R Markdown
  • extends for people who don’t know R Markdown
• Quarto version 1.0 only released July 2022!

We need to start with markup

Now we move to markdown

• There are many markup language on the market
  • html
  • Markdown
  • LaTeX
• Markdown is a lightwieght markup language that you have to use code to add formatting elements to your content.
• Portable, platform independent, and widely used.

How does Quarto work?

Artwork by @allison_horst

Let’s compare a .qmd file with its html output

YAML

• Stands for YAML Ain’t Markup Language
  • Previously stands for Yet Another Markup Language
• Appears at the top of your document.
• YAML is commonly used for configuration files, and starts and ends with ---
• Within the YAML, you can change
  • Author and document information
  • Document type so you can use a single one markdown file to generate many different formats

Why the name “Quarto”?

• Quarto had meaning in the history of publishing, which is the format of a book or pamphlet produced from full sheets printed with eight pages of text, four to a side, then folded twice to produce four leaves.

Why Quarto?

Quarto makes moving between formats straightforward.

Why Quarto? (Cont.)

Quarto enables collaborating across coding languages.

Why Quarto? (Cont.)

Quarto flattens the learning curve.

Getting started!

• Quarto is bundled and comes pre-installed with RStudio v2022.07.1 and beyond!

• If you have an older version of RStudio, please consider updating it.
• Alternatively, please follow the instruction here: https://quarto.org/docs/get-started/.

Creating an Quarto Document in R Studio

Creating an Quarto Document in R Studio (cont.)

• Choose appropriate options.
  • You may want to use the visual markdown editor as your default editor.

• Both .rmd and .qmd are just a plain text file.

Your mission, should you choose to accept it!

pak::pak("tinytex") # uncomment to install the package or
# install.packages("tinytex")
tinytex::install_tinytex()

YAML

YAML (cont.)

• Notice that Quarto can autofill/auto-complete options in your YAML.
  • Press Ctrl + space to list all available YAML options.
  • Press Tab key to auto-complete.

Basic Syntax – Text Formatting

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax.

**bold text**

*italicized text*

***bold and italicized text***

`code`

> Blockquote

Basic Syntax – Equations

inline math: $E = mc^{2}$

display math:

$$E = mc^{2}$$

R Inline code

• Uses a single pair of back ticks and “r”. E.g.

`r 2 + 2 `

• Back ticks are the key in the top left corner of a standard US qwerty keyboard.
• When compiled, the inline command is sent to R for computation.
• The command is then removed from the source document and replaced by the R output.
  • Inline command does not echo and always evaluates (explain more on the next few slides).

R code chunk

• We use code chunk for more complex and larger computation.

```{r cars}
#| include: true
#| echo: false
library(tidyverse)
mtcars %>% 
  filter(cyl == 6)
```

• They are fenced by ```.
  • r: language engine
  • cars: unique chunk name
• You can add customisable options in after {r} brackets i.e. after the chunk name
• You can add chunk options with hashpipe #|:
  • include: include chunk output or not
  • echo: display source code or not

R code chunk (Cont.)

```{r} 
```

```{r cars}
#| message: false
library(tidyverse)
mtcars %>% 
  filter(cyl == 6)
```

R code chunk (Cont.)

• If the message option is set to “true”

library(tidyverse)

── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.1.4     ✔ readr     2.1.4
✔ forcats   1.0.0     ✔ stringr   1.5.1
✔ ggplot2   3.4.4     ✔ tibble    3.2.1
✔ lubridate 1.9.3     ✔ tidyr     1.3.1
✔ purrr     1.0.2     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

Hashpipe (#|)

• Quarto introduces the concept/notation of #| (read the hashpipe).

• Hashpipe enables a more readable way to organise your chunk options.

```{r scatterplot}
#| fig-align: "center"
#| fig-width: 4.5 
#| fig-height: 4
plot(speed ~ dist, cars)
```

Quarto - Visual Editor

Insert Anything trick

• You can also use the catch-all shortcut Cmd + / for Mac or Ctrl + / for Windows within visual editor mode to insert just about anything.
  • If you are at the beginning of a line you can also enter plain / to invoke the shortcut.
• Just execute the shortcut then type what you want to insert (or you can just scroll to find what you need)

Creating a Quarto Presentation in R Studio

• File \(\rightarrow\) New File \(\rightarrow\) Quarto Presentation

• Quarto supports a variety of formats for creating presentations:

  • revealjs – reveal.js (HTML)
  • pptx – PowerPoinst (MS Office)
  • beamer – Beamer (LaTeX/PDF)

Creating a Quarto Presentation in R Studio (Cont.)

• Choose appropriate options (in this case we will choose Presentation).
  • You may want to use the visual markdown editor as your default editor.

Shared syntax across all formats

• Incremental reveal/list
• Multiple columns for layout
• Title/subtitle/author etc
• Headings
• Code/Output

Creating slides

• Slides are delineated using headings. For example, here is a simple slide show with two slides each defined with a level 2 heading (##).

---
title: "Habits"
author: "John Doe"
format: revealjs
---

## Getting up

- Turn off alarm
- Get out of bed

## Going to sleep

- Get in bed
- Count sheep

Incremental Lists

• Controllable via YAML:

---
format: 
  revealjs:
    incremental: true
---

Or turn on/off via fenced divs:

::: {.incremental}
- List element A
- List element B
:::

::: {.nonincremental}
- List element A
- List element B
:::

Multicolumn Columns

• For example the two column layout:

:::: {.columns}

::: {.column width='40%'}
Left column
:::

::: {.column width='60%'}
Right column
:::
::::

and get output:

Addins: Quartostamp

pak::pak("matt-dray/quartostamp")
# or alternatively:
# install.packages("remotes")
# remotes::install_github("matt-dray/quartostamp")

Addins: Quartostamp (cont.)

Your mission, should you choose to accept it!

• Create a quarto presentation using the template in a format of your choice.
  • We recommend you to give all three formats a try to see which one you like.
• Add a new slide.
• Add some code chunks into your presentation and then render it.
• Use quartostamp addin to add different elements and customise your slide deck.
  • Use a two column layout
  • Use one of the callout block.

How does it work?

Creating a quarto presentation in VS Code

Creating a quarto presentation in VS Code (Cont.)

• This is what it looks like if you open a .qmd file:

Creating a quarto presentation in VS Code (Cont.)

• You can also just create a new .qmd file within VS Code

• Notice that the default output format for a quarto presentation is revealjs.

Creating a quarto presentation in VS Code (Cont.)

Creating a quarto presentation in VS Code (Cont.)

Visual Editor in VS Code

VS Code Error

ModuleNotFoundError: No module named 'nbformat'

• Enter the following in the qmd file and run them in VS Code

```{python}
import sys
print(sys.executable)
```

which gives

/usr/local/bin/python3.11

Now that I knew which Python was being used, I could install the nbformat (or any other packages that were missing) in the Terminal with

/usr/local/bin/python3.11 -m pip install nbformat 

We hope…

Thanks!